home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d878.lha / DrChip / hdrtag / hdrtag.doc < prev    next >
Text File  |  1993-06-14  |  6KB  |  142 lines
  1.                Header Tags v1.06 Copyright 1993 Charles E. Campbell, Jr
  2.               ----------------------------------------------------------
  3.  
  4. Copyright:
  5.  
  6.     This program (hdrtag) and associated documents are copyrighted 1993
  7.     by Charles E. Campbell, Jr, PhD.
  8.  
  9.  
  10. Restrictions:
  11.  
  12.     All rights to hdrtag and its documents are reserved, except for those
  13.     explicitly granted herein.
  14.  
  15.     No representation or warranties are made with respect to the accuracy,
  16.     reliability, performance, or operation of this software, and all such
  17.     use is at your own risk.  The author does not assume any responsiblity
  18.     or liability whatsoever with respect to your use of this software.
  19.  
  20.     Hdrtag may not be included with any commercial product nor may it be
  21.     sold for profit either separately or as part of a compilation without
  22.     the permission of Dr. Charles E. Campbell, Jr.  It may be included in
  23.     non-profit disk collections such as the Fred Fish collection.  It may
  24.     be archived and uploaded to electronic bulletin board systems so long
  25.     as all files remain together and unaltered.  It may be copied to and used on
  26.     individuals' computer systems.
  27.  
  28.  
  29. Author : Dr. Charles E. Campbell, Jr.
  30. Contact: cec@gryphon.gsfc.nasa.gov
  31. Version: 1.06
  32.  
  33.  
  34. Usage:
  35.  
  36.     hdrtag [-options] {*.h | directory-names}
  37.     hdrtag "?"
  38.  
  39.  
  40. Options:
  41.  
  42.     -a: use antimagic on patterns
  43.     -Amagic: specify "magic" characters for antimagic
  44.     -g: tag global variables, prototypes, etc
  45.     -h: restrict hdrtag processing to *.h files
  46.     -m: merge hdrtags with tags
  47.     -M: merge hdrtags with current hdrtags
  48.     -p: c++ mode: tag global variables, prototypes, etc
  49.     -r: permit recursive descent down directories (ie. do subdirectories, too)
  50.     -s: system header file handler (fixed, static files)
  51.     -v: verbose mode
  52.     -x: toggle exclude duplicates (default is to exclude)
  53.  
  54.  
  55. Explanation
  56.  
  57.     The hdrtag program examines header files and creates a <hdrtags> file with
  58.     <tags>-style information on how to tag to
  59.  
  60.         structure names
  61.         typedefs
  62.         #define labels
  63.         enum names
  64.         enumerated types
  65.  
  66.     and optionally (-g) to
  67.  
  68.         global variables
  69.         prototype function names
  70.         and anything which is not a C or C++ keyword.
  71.  
  72.     Examples of use:
  73.         cd include:                 # go to your compiler's header files
  74.         hdrtags -garvh include:     # generate a <hdrtags> file
  75.         rename hdrtags tags         # editors use <tags>, not <hdrtags>
  76.         vim -t ARG0                 # go to the file & line where ARG0 is defined
  77.         vim -t putc                 # go find the prototype for putc
  78.         vim -t BPTR                 # go to the file & line wher BPTR is defined
  79.  
  80.     Note that editors (ViM, Z, emacs) use a <tags> file, so hdrtag can optionally
  81.     merge the hdrtags into a pre-existing tags file instead using the -m option.
  82.     
  83.     Alternatively, one may use the flist program with its -m option generate a
  84.     <tags> file and to merge a pre-existing <hdrtags> file into it.  This latter
  85.     method is probably the more useful of the two.
  86.     
  87.     Not all editors use magic characters during tags processing.  ViM, for example,
  88.     only uses a subset of magic characters when it handles tags (ex. the asterisk
  89.     is not magic when its handling tags).  The antimagic facility allows one to
  90.     customize hdrtag's handling of magic characters.
  91.  
  92.     The antimagic facility inserts backslashes (\) before "magic" characters.
  93.     The default set of magic characters is: ^$.[]|\ .  If your favorite program
  94.     needs a different set of magic characters, two methods are provided:
  95.  
  96.         1) use the -Astring (or -A string) option, where the string is your set
  97.            of magic characters
  98.  
  99.         2) set an environment variable, HDRTAGMAGIC, to the magic characters
  100.            your favorite editor needs in tag files.
  101.  
  102.     The hdrtag program will give help with
  103.         hdrtag "?"
  104.  
  105.     For those of you with Aztec C or SAS C, the include: directory hierarchy
  106.     holds your header files.  I suggest using
  107.  
  108.         hdrtag -garvh include:
  109.  
  110.     to process the header files therein.  Doing so, however, will take up over
  111.     3MB of ram.  Afterwards, one may wish to
  112.  
  113.         rename hdrtags tags
  114.  
  115.     and leave the file in the include: directory.  Over 5500 tags will result!
  116.     I'd distribute the resulting tags files myself, but SAS informs me that there
  117.     may be copyright problems with Commodore.  So, please do *not* distribute
  118.     the tags files you generate from the include: hierarchy.
  119.  
  120.     Options are not restricted to appearing at the beginning.  The hdrtag program
  121.     will examine all command line arguments first and process those beginning
  122.     with '-' as options.  One may concatenate arguments (ie. -garvh) or separate
  123.     them (ie. -ga -v -rh).  Options may also be specified with a leading '+'
  124.     which will be processed in sequence with the other arguments
  125.     (ie. hdrtag -a one.h +g two.h).
  126.  
  127.     The -s flag may or may not be useful to you.  On *IX systems, the vi editor
  128.     can tag not only to search strings (/some string where the tagged info is),
  129.     but can tag to a line number.  Obviously, the latter tagline is rather shorter,
  130.     thereby conserving file space and improving tagging times.  Since line
  131.     numbers are used, however, the header files so processed should be more or
  132.     less static, and system header files fit this bill nicely.
  133.  
  134.     The hdrtag program was compiled with Aztec C on an A3000 with the following
  135.     options: CCOPTS=-qf -wp -c2 -f8.  One may wish to move <rdcolor.dat> to the
  136.     s: directory.  The file provides a mapping from color strings to escape
  137.     sequences, and it should be fairly obvious as to how to modify it to suit
  138.     your requirements.
  139.  
  140.     Good luck, and let me know of any problems you encounter, and any attaboys
  141.     will be appreciated :)
  142.